Box, Grid: Improve various bits of documentation
authorDaniel Boles <dboles.src@gmail.com>
Tue, 4 Dec 2018 20:37:08 +0000 (20:37 +0000)
committerDaniel Boles <dboles.src@gmail.com>
Tue, 4 Dec 2018 20:43:19 +0000 (20:43 +0000)
commit72d09d22e934c52ff301c0754078f1e42e97bc69
tree97033def8d25cb206052ae369c3b6a4bac992d0e
parenta2a4603329b42354fed7b73feda7d513a0f00c0f
Box, Grid: Improve various bits of documentation

Issue #1495 showed that the docs of GtkGrid retain outdated implications
that (as was once, but is no longer, the case) it is intended to replace
GtkBox, by discussing HfW and widget properties in a way that suggests
GtkBox can't handle them. But of course it does, and it's preferable for
simple single-row/column cases. Worse, we said GtkGrid “provides exactly
the same functionality” for the latter case, but the original point of
that Issues was that it doesn’t, at least for CSS positional selectors!

Box:
• Use an actually meaningful @Short_description.
• Remove unhelpful @See_also references to unrelated containers.
• Remove references to “rectangular area”: it might be another shape
  via CSS, or “rectangular” might falsely imply 2 dimensions of children.
• Mention Orientable:orientation.
• Emphasise usefulness of :[hv]align for allocating in the other axis.
• Don’t say that Grid “provides exactly the same functionality” for a
  single row or column, since (A) it is overkill for that case and (B)
  said Issue proved that it *doesn’t* for CSS child order, for example.

Grid:
• Don’t dwell on widget properties and height-for-width in a way that
  wrongly implies that Box can’t handle those (or Grid can better). In
  fact, just get rid of that bit altogether: Box handles them fine, and
  such wording was only needed years ago for migration from GTK+ 2 to 3.
• Point to GtkBox as being preferred for the simple row/column use case.
gtk/gtkbox.c
gtk/gtkgrid.c